feat(storybook): expose component docs to agents via official MCP addon (#3527) - #3736
feat(storybook): expose component docs to agents via official MCP addon (#3527)#3736chinawch007 wants to merge 1 commit into
Conversation
…on (apache#3527) Self-host the Storybook MCP endpoint at http://localhost:6006/mcp with only the docs toolset enabled: - install @storybook/addon-mcp in apps/desktop and register it in .storybook/main.ts with dev/test toolsets off (test needs @storybook/addon-vitest and stays a follow-up per the issue) - register the endpoint for agent clients in a new root .mcp.json ("type": "http" client convention; $schema omitted since no official schema covers this client config format) - add AGENTS.md guidance to query the MCP before writing UI code in packages/ui or apps/desktop, preferring existing components Verified: storybook boots unchanged, tools/list exposes exactly the three docs tools, and list-all-documentation / get-documentation / get-documentation-for-story return real story docs over the endpoint. Generated-by: ZCode
Astro-Han
left a comment
There was a problem hiding this comment.
I reviewed this head and found blocking issues.
[P2] MCP addon docs-only claim is not a server boundary and the endpoint is exposed on LAN
@storybook/addon-mcp replaces options via X-MCP-Toolsets (main.ts:45). The live tools/list with a dev header changes from 3 docs tools to 4 dev tools. The storybook script does not bind to loopback, so *:6006 is reachable from 10.7.0.13:6006 without auth — an on-LAN caller can re-enable the dev toolset and obtain a filesystem existence oracle (/etc/passwd vs pathNotFound).
Fix: bind to loopback (and --exact-port) and intersect request-selected toolsets with the configured allowlist; cover with header-injection tests.
[P2] Root .mcp.json is not discovered by Codex
AGENTS.md claims the endpoint is registered, but Codex discovers via .codex/config.toml [mcp_servers], not the Claude-style root JSON. Result: Codex sees the mandatory query instruction but has no tools.
Fix: ship a real project config for each claimed client or narrow the claim; verify via actual client discovery.
Checks on d75281cb67 are test: failure (unrelated CLI EOF backoff flake, but still red — not green). Code issues are independent of CI.
Summary
Agents writing UI code in this repo had no machine-readable interface to
learn which components exist and how to use them, so they grepped and read
component sources to guess props and usage. This PR self-hosts Storybook's
official MCP addon at
http://localhost:6006/mcp, exposing the docstoolset only, so agents can query the existing story catalog before
writing code.
apps/desktop: install@storybook/addon-mcpand register it in.storybook/main.tswithtoolsets: { dev: false, test: false, docs: true }(test toolset needs
@storybook/addon-vitestand stays a follow-up perthe issue)
.mcp.jsonregistering the endpoint for agent clientsAGENTS.md: start Storybook on demand, querylist-all-documentation/get-documentationbefore writing UI code,prefer existing
packages/uicomponentsFixes #3527
Verification
Manual verification succeeded against a running dev server:
npm --workspace @maka/desktop run storybook -- --no-openbootsunchanged; existing stories render as before
MCP
initializeoverPOST /mcpreturns a session idtools/listexposes exactly the three docs tools —list-all-documentation,get-documentation,get-documentation-for-story— confirming thedev/test toolsets are off:
all three tools return real content, e.g.
get-documentationforprimitives-toastreturns the story list with usage snippetsnpm run lintandnpm run format:checkpassNot run / known gaps: full
npm run buildandnpm test(config-onlychange, no unit suite covers Storybook config); desktop-workspace
typecheck reports 40 pre-existing errors that reproduce identically on
clean
mainin this environment (stale workspace dists) — none touch thechanged files, which typecheck clean.
Review focus
.mcp.jsonuses the"type": "http"+"url"client convention(Claude Code / Cursor-class agent CLIs), not an MCP spec format; it is
dev-time tooling config, unrelated to
packages/mcp's product config.$schemais omitted — no official schema covers this client format..github/copilot-instructions.md(code-review guidance only) and the newAGENTS.mdcover disjoint topics;AGENTS.mdis the cross-toolcanonical location. Mirroring into copilot-instructions.md is left as a
maintainer decision.
AI use
Select exactly one:
Tool(s) and scope: ZCode authored the config and documentation changes and
ran the verification above; the human contributor reviewed the result and
performed the final verification on a live server.
Checklist
Does this PR entail a change in behavior?